Document how BoxFutures / BoxStreams are often made
#2887
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
alamb
commented
Oct 3, 2024
| @@ -9,6 +9,11 @@ pub use core::future::Future; | |||
|
|
|||
| /// An owned dynamically typed [`Future`] for use in cases where you can't | |||
| /// statically type your result or need to add some indirection. | |||
| /// | |||
There was a problem hiding this comment.
This follows the wording and pattern in std, for example https://doc.rust-lang.org/std/iter/struct.Cloned.html
This struct is created by the cloned method on Iterator. See its documentation for more.
Here is how it looks rendered:
alamb
commented
Oct 3, 2024
| /// This type is often created by the [`boxed`] method on [`FutureExt`]. See its documentation for more. | ||
| /// | ||
| /// [`boxed`]: https://docs.rs/futures/latest/futures/future/trait.FutureExt.html#method.boxed | ||
| /// [`FutureExt`]: https://docs.rs/futures/latest/futures/future/trait.FutureExt.html |
There was a problem hiding this comment.
this links back to docs.rs because futures-core does not depened on futures-util, where FutureExt is defined
|
FYI @taiki-e |
|
Thanks! This seems reasonable to me. |
taiki-e
added
docs
0.3-backport: pending
|
Could you add similar docs to other boxed types? |
Yes, I will do so |
alamb
changed the title
BoxFutures are often madeBoxFutures / BoxStreams are often made
Done |
taiki-e
approved these changes
Oct 4, 2024
|
Thank you again @taiki-e |
taiki-e
pushed a commit
that referenced
this pull request
Oct 5, 2024
Merged
taiki-e
pushed a commit
that referenced
this pull request
Oct 5, 2024
taiki-e
added
0.3-backport: completed
and removed
0.3-backport: pending
taiki-e
pushed a commit
that referenced
this pull request
Oct 5, 2024
# for free
to join this conversation on GitHub.
Already have an account?
# to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Rationale
Unless you are already familiar with the Rust futures ecosystem and
FuturesExt::boxedit is not always obvious how to create aBoxFutureSpecifically, we have APIs for reading parquet files, which involve
BoxFutures that when a user clicks on the return type,The documentation doesn't lead them to
FutureExt::boxed:Proposal
While a better improvement for our users is a full featured example (added in apache/arrow-rs#6505), I think this to propose improvements in this crate too to help the broader community
If the maintainers like this pattern, I am happy to add it for other similar types in Futures and Streams but I won't bother if you are not interested in this type of change